---
title: 将实时智能体连接到 Twilio
description: Connect your Agents SDK agents to Twilio to use voice agents
---

import { Aside, Steps, Code } from '@astrojs/starlight/components';
import twilioBasicExample from '../../../../../../examples/docs/extensions/twilio-basic.ts?raw';
import twilioServerExample from '../../../../../../examples/realtime-twilio/index.ts?raw';

Twilio 提供了一个 [Media Streams API](https://www.twilio.com/docs/voice/media-streams)，可将电话通话中的原始音频发送到一个 WebSocket 服务器。通过该设置，您可以将[语音智能体](/openai-agents-js/zh/guides/voice-agents)连接到 Twilio。您可以使用 `websocket` 模式下的默认 Realtime Session 传输机制，将来自 Twilio 的事件连接到您的 Realtime Session。不过，这需要您设置正确的音频格式，并调整自己的打断时机，因为电话通话相比基于 Web 的对话会自然引入更多延迟。

为改进搭建体验，我们创建了一个专用的传输层，为您处理与 Twilio 的连接，包括中断处理和音频转发。

<Aside type="caution">
  该适配器仍处于测试阶段。您可能会遇到边界情况或漏洞。 请通过 [GitHub
  issues](https://github.com/openai/openai-agents-js/issues)
  报告任何问题，我们会尽快修复。
</Aside>

## 设置

<Steps>

1. **确保您拥有 Twilio 账户和一个 Twilio 电话号码。**

2. **搭建一个可接收来自 Twilio 事件的 WebSocket 服务器。**

   如果您在本地开发，这需要配置一个本地隧道，例如使用 [`ngrok`](https://ngrok.io/) 或
   [Cloudflare Tunnel](https://developers.cloudflare.com/pages/how-to/preview-with-cloudflare-tunnel/)
   使您的本地服务器可被 Twilio 访问。您可以使用 `TwilioRealtimeTransportLayer`
   连接到 Twilio。

3. **通过安装扩展包来安装 Twilio 适配器：**

   ```bash
   npm install @openai/agents-extensions
   ```

4. **导入适配器和模型以连接您的 `RealtimeSession`：**

   <Code
     lang="typescript"
     code={twilioBasicExample.replace(
       /\n\s+\/\/ @ts-expect-error - this is not defined/g,
       '',
     )}
   />

5. **将您的 `RealtimeSession` 连接到 Twilio：**

   ```typescript
   session.connect({ apiKey: 'your-openai-api-key' });
   ```

</Steps>

任何您期望从 `RealtimeSession` 获得的事件与行为（包括工具调用、护栏等）都将如预期工作。阅读[语音智能体概述](/openai-agents-js/zh/guides/voice-agents)了解如何将 `RealtimeSession` 与语音智能体搭配使用的更多信息。

## 提示与注意事项

1. **速度至关重要。**

   为了接收来自 Twilio 的所有必要事件与音频，您应在获得 WebSocket 连接引用后立刻创建
   `TwilioRealtimeTransportLayer` 实例，并立即调用 `session.connect()`。

2. **访问原始 Twilio 事件。**

   如果您需要访问 Twilio 发送的原始事件，可以监听 `RealtimeSession` 实例上的
   `transport_event` 事件。来自 Twilio 的每个事件都会有 `twilio_message` 类型，以及包含原始事件数据的 `message` 属性。

3. **查看调试日志。**

   有时您可能会遇到需要更多信息来排查的问题。使用环境变量 `DEBUG=openai-agents*` 将显示来自 Agents SDK 的所有调试日志。或者，您也可以仅启用 Twilio 适配器的调试日志：`DEBUG=openai-agents:extensions:twilio*`。

## 完整示例服务器

下面是一个端到端的 WebSocket 服务器示例，用于接收来自 Twilio 的请求并将其转发到 `RealtimeSession`。

<Code
  lang="typescript"
  code={twilioServerExample}
  title="使用 Fastify 的示例服务器"
/>
